pg_dbml is a CLI tool that introspects a PostgreSQL database and exports its complete schema—tables, columns, constraints, indexes, foreign keys, and comments—into DBML (Database Markup Language) format using a single pure SQL query.

How do I install pg_dbml?

The easiest way is via Homebrew: brew install heptau/tap/pg-dbml. Alternatively, clone the repository from GitHub (git clone https://github.com/heptau/pg_dbml.git), run chmod +x pg_dbml, and optionally create a symlink to /usr/local/bin.

Does pg_dbml require any external dependencies?

No. pg_dbml only requires psql (the standard PostgreSQL client) in your PATH. The introspection logic is a single pure SQL query with no external libraries, ORMs, or configuration files.

What PostgreSQL objects does pg_dbml export?

pg_dbml exports all user tables across all schemas, including: column names and normalized data types, primary keys, unique constraints, NOT NULL constraints, default values, indexes (including composite and INCLUDE columns), foreign key references, and table and column comments.

Why use DBML for AI and LLMs?

DBML is a compact, structured, human-readable format that LLMs can parse efficiently. Providing your database schema as DBML gives AI assistants instant understanding of table relationships, constraints, and data types without requiring live database access or complex SQL introspection.

PostgreSQL → DBML

pg_dbml

Database Schema Extractor

Export your entire PostgreSQL schema to DBML format with a single command. Pure SQL, zero external dependencies.

View on GitHub Quick Start ↓

terminal

# Export schema to DBML

$ ./pg_dbml \

--host localhost \

--dbname my_database \

--output schema.dbml

✓ Schema successfully exported → schema.dbml▌

What is pg_dbml?

pg_dbml is a powerful command-line tool designed to introspect your PostgreSQL database schema and export its complete structure to Database Markup Language (DBML) format. It achieves this by executing complex, pure SQL queries against PostgreSQL system catalogs, ensuring 100% schema fidelity without needing external drivers or ORMs.

💡 Why use DBML for AI & LLMs?

Database schemas are often complex to parse. Querying a live database for schema knowledge is slow, resource-intensive, and requires intricate SQL expertise. DBML solves this by providing a human-readable, declarative, and highly structured blueprint of your data.

✦ Benefit for AI

By consuming a DBML file, large language models (LLMs) can rapidly and cost-effectively familiarize themselves with your data model. They can instantly understand relationships, table structures, and constraints without running time-consuming queries against the live database.

Key Features

⬡

Pure SQL Introspection

The logic is entirely contained within PostgreSQL queries — no external dependencies.

⛓

Constraint Mapping

Automatically detects and maps Primary Keys, Unique constraints, and Foreign Key relationships.

◈

Index Overview

Documents custom indexes and INCLUDE columns for full schema coverage.

◉

Metadata Richness

Includes table and column comments retrieved directly from PostgreSQL metadata.

▶

CLI Driven

Simple, repeatable execution via the pg_dbml command. Perfect for scripts and CI/CD.

Installation

🍺

Homebrew (Recommended)

The easiest way to install on macOS and Linux. Automatically handles all dependencies.

$ brew install heptau/tap/pg-dbml

⚙

Manual Installation

For systems without Homebrew or if you prefer manual control.

Clone the repository

git clone https://github.com/heptau/pg_dbml.git

Make it executable

chmod +x pg_dbml

Symlink (Optional)

For global availability:

ln -s $(pwd)/pg_dbml /usr/local/bin/pg_dbml

* Requires psql installed and available in your PATH.

Usage & Parameters

You can run pg_dbml using individual parameters or a standard PostgreSQL Connection URI.

Basic Execution

terminal

# Export by database name

$ pg_dbml -d my_database -o schema.dbml

# The database name can also be a plain positional argument

$ pg_dbml my_database

Connection defaults

Connection parameters are forwarded to psql only when you actually provide them. Everything you omit falls back to psql's own defaults and the standard environment variables (PGHOST, PGPORT, PGUSER, PGDATABASE). If your environment is already set up for psql, running it with no arguments at all works too.

terminal

$ export PGHOST=db.internal PGUSER=reporting PGDATABASE=analytics

$ pg_dbml

Using Connection URI

terminal

# Export using full URI

$ pg_dbml postgresql://user:pass@localhost:5432/my_db

Preview (dry-run)

terminal

# Preview output without writing file

$ pg_dbml -d mydb --dry-run

Parameters Overview

Parameter	Short	Description	Default
`--dbname`	`-d`	Name of the target database.	`$PGDATABASE`
`--host`	`-h`	PostgreSQL host address.	`$PGHOST`
`--port`	`-p`	PostgreSQL port.	`$PGPORT`
`--user`	`-U`	Database user name.	`$PGUSER`
`--output`	`-o`	Path where the .dbml file will be saved.	`[DBNAME].dbml`
`--quiet`	`-q`	Suppress success message.	-
`--dry-run`	-	Preview output without writing file.	-
`--version`	`-v`	Show script version.	-

Technical Architecture

The project is split into two parts to maximize developer experience and maintainability:

pg_dbml (Bash orchestrator)

Parses arguments, handles database connections via psql, and writes the output.

pg_dbml.sql (Core Engine)

A complex, pure SQL query. Keeping it separate allows for full syntax highlighting and standard SQL debugging.